home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 January: Mac OS SDK / Dev.CD Jan 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Interfaces / CIncludes / NameRegistry.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-01-15  |  11.0 KB  |  354 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        NameRegistry.h
  3.  
  4.      Contains:    NameRegistry Interfaces .
  5.  
  6.      Version:    Technology:    PowerSurge 1.0.2.
  7.                  Package:    Universal Interfaces 2.1.2 on ETO #20
  8.  
  9.      Copyright:    © 1984-1995 by Apple Computer, Inc.
  10.                  All rights reserved.
  11.  
  12.      Bugs?:        If you find a problem with this file, use the Apple Bug Reporter
  13.                  stack.  Include the file and version information (from above)
  14.                  in the problem description and send to:
  15.                      Internet:    apple.bugs@applelink.apple.com
  16.                      AppleLink:    APPLE.BUGS
  17.  
  18. */
  19.  
  20. #ifndef __NAMEREGISTRY__
  21. #define __NAMEREGISTRY__
  22.  
  23.  
  24. #ifndef __TYPES__
  25. #include <Types.h>
  26. #endif
  27. /*    #include <ConditionalMacros.h>                                */
  28.  
  29. #ifdef __cplusplus
  30. extern "C" {
  31. #endif
  32.  
  33. #if PRAGMA_ALIGN_SUPPORTED
  34. #pragma options align=mac68k
  35. #endif
  36.  
  37. #if PRAGMA_IMPORT_SUPPORTED
  38. #pragma import on
  39. #endif
  40.  
  41. typedef void *RegPropertyValue;
  42.  
  43. /* Length of property value */
  44. typedef UInt32 RegPropertyValueSize;
  45.  
  46. /* Namespace generation number */
  47. typedef UInt32 RegSpecGeneration;
  48.  
  49. /* ******************************************************************************
  50. ** 
  51. ** RegEntryID    :    The Global x-Namespace Entry Identifier
  52. //
  53. */
  54. struct RegEntryID {
  55.     UInt8                            opaque[16];
  56. };
  57. typedef struct RegEntryID RegEntryID, *RegEntryIDPtr;
  58.  
  59. /* ******************************************************************************
  60. **
  61. ** Root Entry Name Definitions    (Applies to all Names in the RootNameSpace)
  62. //
  63. //    * Names are a colon separated list of name components.  Name components
  64. //      may not themselves contain colons.  
  65. //    * Names are presented as null terminated Unicode character strings.
  66. //    * Names follow similar parsing rules to Apple file system absolute
  67. //      and relative paths.  However the '::' parent directory syntax is
  68. //      not currently supported.
  69. */
  70. /* Max length of Entry Name */
  71.  
  72. enum {
  73.     kRegCStrMaxEntryNameLength    = 47
  74. };
  75.  
  76. /* Entry Names are single byte ASCII */
  77. typedef char RegCStrEntryName, *RegCStrEntryNamePtr, RegCStrEntryNameBuf[kRegCStrMaxEntryNameLength + 1];
  78.  
  79. typedef char RegCStrPathName;
  80.  
  81. typedef UInt32 RegPathNameSize;
  82.  
  83.  
  84. enum {
  85.     kRegPathNameSeparator        = 0x3A,                            /* ':'  */
  86.     kRegEntryNameTerminator        = 0x00,                            /* '\0' */
  87.     kRegPathNameTerminator        = 0x00                            /* '\0' */
  88. };
  89.  
  90. /* ******************************************************************************
  91. **
  92. ** Property Name and ID Definitions
  93. //    (Applies to all Properties Regardless of NameSpace)
  94. */
  95. enum {
  96.     kRegMaximumPropertyNameLength = 31,                            /* Max length of Property Name */
  97.     kRegPropertyNameTerminator    = 0x00                            /* '\0' */
  98. };
  99.  
  100. typedef char RegPropertyName, *RegPropertyNamePtr, RegPropertyNameBuf[kRegMaximumPropertyNameLength + 1];
  101.  
  102. /* ******************************************************************************
  103. **
  104. ** Iteration Operations
  105. //
  106. //    These specify direction when traversing the name relationships
  107. */
  108. typedef UInt32 RegIterationOp;
  109.  
  110. typedef RegIterationOp RegEntryIterationOp;
  111.  
  112.  
  113. enum {
  114. /*
  115.     ** Absolute locations
  116.     */
  117.     kRegIterRoot                = 0x2UL,
  118. /*
  119.     ** "Upward" Relationships    
  120.     */
  121.     kRegIterParents                = 0x3UL,                        /* include all  parent(s) of entry */
  122. /*
  123.     ** "Downward" Relationships
  124.     //
  125.     */
  126.     kRegIterChildren            = 0x4UL,                        /* include all children */
  127.     kRegIterSubTrees            = 0x5UL,                        /* include all sub trees of entry */
  128.     kRegIterDescendants            = 0x5UL,                        /* include all descendants of entry */
  129. /*
  130.     ** "Horizontal" Relationships    
  131.     */
  132.     kRegIterSibling                = 0x6UL,                        /* include all siblings */
  133. /*
  134.     ** Keep doing the same thing
  135.     */
  136.     kRegIterContinue            = 0x1UL
  137. };
  138.  
  139. /* ******************************************************************************
  140. **
  141. ** Name Entry and Property Modifiers
  142. //
  143.  
  144. //
  145. // Modifiers describe special characteristics of names
  146. // and properties.  Modifiers might be supported for
  147. // some names and not others.
  148. // 
  149. // Device Drivers should not rely on functionality
  150. // specified as a modifier.
  151. */
  152. typedef UInt32 RegModifiers;
  153.  
  154. typedef RegModifiers RegEntryModifiers;
  155.  
  156. typedef RegModifiers RegPropertyModifiers;
  157.  
  158.  
  159. enum {
  160.     kRegNoModifiers                = 0x00000000UL,                    /* no entry modifiers in place */
  161.     kRegUniversalModifierMask    = 0x0000FFFFUL,                    /* mods to all entries */
  162.     kRegNameSpaceModifierMask    = 0x00FF0000UL,                    /* mods to all entries within namespace */
  163.     kRegModifierMask            = 0xFF000000UL                    /* mods to just this entry */
  164. };
  165.  
  166. /* Universal Property Modifiers */
  167. enum {
  168.     kRegPropertyValueIsSavedToNVRAM = 0x00000020UL,                /* property is non-volatile (saved in NVRAM) */
  169.     kRegPropertyValueIsSavedToDisk = 0x00000040UL                /* property is non-volatile (saved on disk) */
  170. };
  171.  
  172. /* ***********************
  173. **
  174. ** The Registry API
  175. //
  176. /////////////////////// */
  177. /* ***********************
  178. **
  179. ** Entry Management
  180. //
  181. /////////////////////// */
  182. /*-------------------------------
  183.  * EntryID handling
  184.  */
  185. /*
  186.  * Initialize an EntryID to an known invalid state
  187.  *   note: invalid != uninitialized
  188.  */
  189. extern OSStatus RegistryEntryIDInit(RegEntryID *id);
  190. /*
  191.  * Compare EntryID's for equality or if invalid
  192.  *
  193.  * If a NULL value is given for either id1 or id2 the other id 
  194.  * is compared with and invalid ID.  If both are NULL, the id's 
  195.  * are consided equal (result = true). 
  196.  */
  197. extern Boolean RegistryEntryIDCompare(const RegEntryID *id1, const RegEntryID *id2);
  198. /*
  199.  * Copy an EntryID
  200.  */
  201. extern OSStatus RegistryEntryIDCopy(const RegEntryID *src, RegEntryID *dst);
  202. /*
  203.  * Free an ID so it can be reused.
  204.  */
  205. extern OSStatus RegistryEntryIDDispose(RegEntryID *id);
  206. /*-------------------------------
  207.  * Adding and removing entries
  208.  *
  209.  * If (parentEntry) is NULL, the name is assumed
  210.  * to be a rooted path. It is rooted to an anonymous, unnamed root.
  211.  */
  212. extern OSStatus RegistryCStrEntryCreate(const RegEntryID *parentEntry, const RegCStrPathName *name, RegEntryID *newEntry);
  213. extern OSStatus RegistryEntryDelete(const RegEntryID *id);
  214. struct RegEntryIter {
  215.     void                            *opaque;
  216. };
  217. typedef struct RegEntryIter *RegEntryIterPtr;
  218.  
  219. typedef struct RegEntryIter RegEntryIter;
  220.  
  221. /* 
  222.  * create/dispose the iterator structure
  223.  *   defaults to root with relationship = kReIterDescendants
  224.  */
  225. extern OSStatus RegistryEntryIterateCreate(RegEntryIter *cookie);
  226. extern OSStatus RegistryEntryIterateDispose(RegEntryIter *cookie);
  227. /* 
  228.  * set Entry Iterator to specified entry
  229.  */
  230. extern OSStatus RegistryEntryIterateSet(RegEntryIter *cookie, const RegEntryID *startEntryID);
  231. /*
  232.  * Return each value of the iteration
  233.  *
  234.  * return entries related to the current entry
  235.  * with the specified relationship
  236.  */
  237. extern OSStatus RegistryEntryIterate(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done);
  238. /*
  239.  * return entries with the specified property
  240.  *
  241.  * A NULL RegPropertyValue pointer will return an
  242.  * entry with the property containing any value.
  243.  */
  244. extern OSStatus RegistryEntrySearch(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done, const RegPropertyName *propertyName, const void *propertyValue, RegPropertyValueSize propertySize);
  245. /*--------------------------------
  246.  * Find a name in the namespace
  247.  *
  248.  * This is the fast lookup mechanism.
  249.  * NOTE:  A reverse lookup mechanism
  250.  *      has not been provided because
  251.  *        some name services may not
  252.  *        provide a fast, general reverse
  253.  *        lookup.
  254.  */
  255. extern OSStatus RegistryCStrEntryLookup(const RegEntryID *searchPointID, const RegCStrPathName *pathName, RegEntryID *foundEntry);
  256. /*---------------------------------------------
  257.  * Convert an entry to a rooted name string
  258.  *
  259.  * A utility routine to turn an Entry ID
  260.  * back into a name string.
  261.  */
  262. extern OSStatus RegistryEntryToPathSize(const RegEntryID *entryID, RegPathNameSize *pathSize);
  263. extern OSStatus RegistryCStrEntryToPath(const RegEntryID *entryID, RegCStrPathName *pathName, RegPathNameSize pathSize);
  264. /*
  265.  * Parse a path name.
  266.  *
  267.  * Retrieve the last component of the path, and
  268.  * return a spec for the parent.
  269.  */
  270. extern OSStatus RegistryCStrEntryToName(const RegEntryID *entryID, RegEntryID *parentEntry, RegCStrEntryName *nameComponent, Boolean *done);
  271. /* ******************************************************
  272. **
  273. ** Property Management
  274. //
  275. ////////////////////////////////////////////////////// */
  276. /*-------------------------------
  277.  * Adding and removing properties
  278.  */
  279. extern OSStatus RegistryPropertyCreate(const RegEntryID *entryID, const RegPropertyName *propertyName, const void *propertyValue, RegPropertyValueSize propertySize);
  280. extern OSStatus RegistryPropertyDelete(const RegEntryID *entryID, const RegPropertyName *propertyName);
  281. /*---------------------------
  282.  * Traversing the Properties of a name
  283.  *
  284.  */
  285. struct RegPropertyIter {
  286.     void                            *opaque;
  287. };
  288. typedef struct RegPropertyIter *RegPropertyIterPtr;
  289.  
  290. typedef struct RegPropertyIter RegPropertyIter;
  291.  
  292. extern OSStatus RegistryPropertyIterateCreate(const RegEntryID *entry, RegPropertyIter *cookie);
  293. extern OSStatus RegistryPropertyIterateDispose(RegPropertyIter *cookie);
  294. extern OSStatus RegistryPropertyIterate(RegPropertyIter *cookie, RegPropertyName *foundProperty, Boolean *done);
  295. /*
  296.  * Get the value of the specified property for the specified entry.
  297.  *
  298.  */
  299. extern OSStatus RegistryPropertyGetSize(const RegEntryID *entryID, const RegPropertyName *propertyName, RegPropertyValueSize *propertySize);
  300. /*
  301.  * (*siz) is the maximum size of the value returned in the buffer
  302.  * pointer to by (val).  Upon return, (*siz) is the size of the
  303.  * value returned.
  304.  */
  305. extern OSStatus RegistryPropertyGet(const RegEntryID *entryID, const RegPropertyName *propertyName, void *propertyValue, RegPropertyValueSize *propertySize);
  306. extern OSStatus RegistryPropertySet(const RegEntryID *entryID, const RegPropertyName *propertyName, const void *propertyValue, RegPropertyValueSize propertySize);
  307. /* ******************************************************
  308. **
  309. ** Modibute (err, I mean Modifier) Management
  310. //
  311. ////////////////////////////////////////////////////// */
  312. /*
  313.  * Modifiers describe special characteristics of names
  314.  * and properties.  Modifiers might be supported for
  315.  * some names and not others.
  316.  * 
  317.  * Device Drivers should not rely on functionality
  318.  * specified as a modifier.  These interfaces
  319.  * are for use in writing Experts.
  320.  */
  321. /*
  322.  * Get and Set operators for entry modifiers
  323.  */
  324. extern OSStatus RegistryEntryGetMod(const RegEntryID *entry, RegEntryModifiers *modifiers);
  325. extern OSStatus RegistryEntrySetMod(const RegEntryID *entry, RegEntryModifiers modifiers);
  326. /*
  327.  * Get and Set operators for property modifiers
  328.  */
  329. extern OSStatus RegistryPropertyGetMod(const RegEntryID *entry, const RegPropertyName *name, RegPropertyModifiers *modifiers);
  330. extern OSStatus RegistryPropertySetMod(const RegEntryID *entry, const RegPropertyName *name, RegPropertyModifiers modifiers);
  331. /*
  332.  * Iterator operator for entry modifier search
  333.  */
  334. extern OSStatus RegistryEntryMod(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done, RegEntryModifiers matchingModifiers);
  335. /*
  336.  * Iterator operator for entries with matching 
  337.  * property modifiers
  338.  */
  339. extern OSStatus RegistryEntryPropertyMod(RegEntryIter *cookie, RegEntryIterationOp relationship, RegEntryID *foundEntry, Boolean *done, RegPropertyModifiers matchingModifiers);
  340.  
  341. #if PRAGMA_IMPORT_SUPPORTED
  342. #pragma import off
  343. #endif
  344.  
  345. #if PRAGMA_ALIGN_SUPPORTED
  346. #pragma options align=reset
  347. #endif
  348.  
  349. #ifdef __cplusplus
  350. }
  351. #endif
  352.  
  353. #endif /* __NAMEREGISTRY__ */
  354.